crate-jdbc requires >= 11 (https://github.com/crate/crate-jdbc/blob/master/build.gradle#L19). Also the given command does not required JEP 330 afaik.

JEP 330

Hi. We see that JEP 330 landed with Java 11 already, so this comment is certainly misguided; thanks for spotting it.

Apparently, the fourth mode for the Java launcher to launch a class declared in a source file has been added a long time ago already.

java HelloWorld.java

We may have been confused about it, because we don't launch Java programs so often, so we didn't know about this option before, expecting that launching a program requires an incantation of javac beforehand.

JEP 445

However, the example above uses this feature already:

Java 21 introduces unnamed classes to make the class declaration implicit. Also public static void main(String args[]) is no longer required, to reduce boilerplate for single-class programs.

So, this effectively needs JEP 445 which landed with Java 21. Comparing those snippets, it saves a few bytes, class noise, a whole indentation level, and any "naming things" obstacles regarding Java specifics in file name vs. class name discrepancies.

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

void main() {
    System.out.println("Hello, World!");
}

Thoughts / Evaluation

So, is it worth to sacrifice backward compatibility for the canonical poster example?

My thoughts were we indeed could do it, because the other spot where canonical code examples are presented, in this case cratedb-examples:by-language/java-jdbc, displays a full Java program BasicPostgresCrateDB.java anyway.

In this spirit, we wanted to reduce boilerplate to the max here, yet retaining the idea of presenting an executable example. It's a narrow path which sometimes needs modern language features, or utility programs like uv for elegantly launching Python code snippets, where the user/reader mostly needed to whip up a whole programming environment (Python virtualenv) before even getting started.

Following this idea and the modernization efforts of upstream software authors who work on such ergonomic enhancements, we have been aiming to present "modern" variants of how to minimally invoke arbitrary code snippets on our documentation as well.

Evaluation / Next steps

We can collectively decide if it's okay to present the modern variants while sacrificing backwards compatibility with previous programming language versions, but sure we should present information which accompanies older versions as well.

Let me come up with another iteration on this document to accomodate a better balance for Java < 21, so you can evaluate and decide if you like it.

crate-jdbc requires >= 11

We will certainly add this remark about the effective runtime dependency separately and more prominently, thank you.

Addressed with 0fff874 and dcce170, then ba1ed79, thank you.

At the top, the page now says:

CrateDB JDBC needs Java >= 11.

Only at the bottom when it's about invoking the code snippet at hand, which is primarily thought to be a descriptive example ¹, it says:

Invoke program. Needs Java >= 21 (JEP 445), alternatively see Full example.

Is it worth to sacrifice backward compatibility for the canonical poster example?

My thoughts were we indeed could do it, because the other spot where canonical code examples are presented, in this case cratedb-examples:by-language/java-jdbc, displays a full Java program BasicPostgresCrateDB.java anyway, [and it is referenced right at the bottom of the page].

The adjustment 5d5de24 further makes this less of an issue, by bringing both spots much closer together now.

Let me also correct my previous statements about JEP 445: The minimal code example needs JEP 512, which is in effect with Java 25.

also:

Improved with 59b8ea3, thanks.

PostgreSQL-JDBC works with Java >= 1.8, and the given command does not need JEP 330 afaik.

Thanks, this is important information for some. We will highlight runtime version compatibility more prominently.

Addressed inside 0fff874, thank you.

JEP 330

Hi. We see that JEP 330 landed with Java 11 already, so this comment is certainly misguided; thanks for spotting it.

Apparently, the fourth mode for the Java launcher to launch a class declared in a source file has been added a long time ago already.

java HelloWorld.java

We may have been confused about it, because we don't launch Java programs so often, so we didn't know about this option before, expecting that launching a program requires an incantation of javac beforehand.

JEP 445

However, the example above uses this feature already:

Java 21 introduces unnamed classes to make the class declaration implicit. Also public static void main(String args[]) is no longer required, to reduce boilerplate for single-class programs.

So, this effectively needs JEP 445 which landed with Java 21. Comparing those snippets, it saves a few bytes, class noise, a whole indentation level, and any "naming things" obstacles regarding Java specifics in file name vs. class name discrepancies.

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

void main() {
    System.out.println("Hello, World!");
}

Thoughts / Evaluation

So, is it worth to sacrifice backward compatibility for the canonical poster example?

My thoughts were we indeed could do it, because the other spot where canonical code examples are presented, in this case cratedb-examples:by-language/java-jdbc, displays a full Java program BasicPostgresCrateDB.java anyway.

In this spirit, we wanted to reduce boilerplate to the max here, yet retaining the idea of presenting an executable example. It's a narrow path which sometimes needs modern language features, or utility programs like uv for elegantly launching Python code snippets, where the user/reader mostly needed to whip up a whole programming environment (Python virtualenv) before even getting started.

Following this idea and the modernization efforts of upstream software authors who work on such ergonomic enhancements, we have been aiming to present "modern" variants of how to minimally invoke arbitrary code snippets on our documentation as well.

Evaluation / Next steps

We can collectively decide if it's okay to present the modern variants while sacrificing backwards compatibility with previous programming language versions, but sure we should present information which accompanies older versions as well.

Let me come up with another iteration on this document to accomodate a better balance for Java < 21, so you can evaluate and decide if you like it.

crate-jdbc requires >= 11

We will certainly add this remark about the effective runtime dependency separately and more prominently, thank you.

Thanks, this is important information for some. We will highlight runtime version compatibility more prominently.

While being at it, let's unflatten this page a bit more, like others are doing it, probably by using information cards.

Secondly, another possibility is to go further and also relocate the content currently slotted into the topics section, which is bound to be dissolved anyway. Here, closer to its primary topic domain Java, the content would be located much better.

Secondly, another possibility is to go further and also relocate the content currently slotted into the topics section, which is bound to be dissolved anyway.

Excellent. Implemented per ff18c5b.

-- https://cratedb-guide--402.org.readthedocs.build/connect/java/testing.html

The dropdown reduces clutter/noise significantly already, still it obstructs the reading flow. Consider three things for the next iteration:

a) Provide the download link also per HTML link anchor <a href=""></a>, to better support browser users as already mentioned, freeing them from needing to copy/paste the URL.

b) Relocate all special considerations (wget or Invoke-WebRequest) to the bottom of the page.

c) Alternatively to b), add instructions for both operation system variants (wget and Invoke-WebRequest) to the dropdown, but keep it in this section without relocation.

I've relocated all the instruction noise to the bottom of the pages per dcce170 now, so the synopsis is more in the focus, followed by (typical) installation instructions, with the quickstart example only at the bottom of the page. I think the pages are much more approachable now, and convey their information in the right order.

-- https://cratedb-guide--402.org.readthedocs.build/connect/java/postgresql-jdbc.html
-- https://cratedb-guide--402.org.readthedocs.build/connect/java/cratedb-jdbc.html

More command noise reduction per 5d5de24, we think information absorption is pretty swift now.